4.1 Understanding Explanations

Failed should forms are reported like this:

F addition-test
    (ert-test-failed
     ((should
       (=
        (+ 1 2)
        4))
      :form
      (= 3 4)
      :value nil))

ERT shows what the should expression looked like and what values its subexpressions had: The source code of the assertion was (should (= (+ 1 2) 4)), which applied the function = to the arguments 3 and 4, resulting in the value nil. In this case, the test is wrong; it should expect 3 rather than 4.

If a predicate like equal is used with should, ERT provides a so-called explanation:

F list-test
    (ert-test-failed
     ((should
       (equal
        (list 'a 'b 'c)
        '(a b d)))
      :form
      (equal
       (a b c)
       (a b d))
      :value nil :explanation
      (list-elt 2
                (different-atoms c d))))

In this case, the function equal was applied to the arguments (a b c) and (a b d). ERT’s explanation shows that the item at index 2 differs between the two lists; in one list, it is the atom c, in the other, it is the atom d.

In simple examples like the above, the explanation is unnecessary. But in cases where the difference is not immediately apparent, it can save time:

F test1
    (ert-test-failed
     ((should
       (equal x y))
      :form
      (equal a a)
      :value nil :explanation
      (different-symbols-with-the-same-name a a)))

ERT only provides explanations for predicates that have an explanation function registered. See Defining Explanation Functions.